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There are several proprietary software packages available that provide the user with 
documentation aids. IBM’s AUTOCHART and Applied Data Research’s AUTOFLOW are 
examples of flowchart generators. For many years, it has been the flowchart that provides 
the key to good program documentation. Flowcharts are invaluable for documenting ma- 
chine language programs; they are only slightly less helpful with large FORTRAN and 
COBOL programs. However, flowcharts are not necessarily the most important pieces of 
documentation for medium-size, compiler-level programs. 

With this in mind, a documentation program was developed in which the emphasis is 
placed on text content rather than flowcharting. Grumman Data Systems has been using this 
program for 1 year to document most of its production-type programs. There are personnel 
whose sole responsibility is to prepare these production jobs for computer runs. Each of these 
individuals must know how to prepare several different jobs for runs on the computer. This 
arrangement permits the programmer to write, debug, and then turn over his program along 
with a copy of his documentation to deck assembly personnel for production use. 

The documentation that accompanies the debugged program is often called operational 
documentation. Such documentation usually includes all parts of the complete document 
except the source listings. A typical document would include the following: 

(1 ) Accounting information (deck number, job charge numbers, etc.) 

(2) General description (an abstract of the program explaining how it fits into the 
overall data flow and subroutine descriptions) 

(3) Functional flowcharts (Detailed flowcharts are not considered necessary because of 
the type of work done by batch programmers. Few programs of any size are reused 
once their primary job requirement has ended. In most cases, if a future task has 
need for a similar program, a new program is written, rather than rework an old 
program.) 

(4) Data card formats, deck setups, and options 

These four sections appear in all operational documentation. The programming department 
retains a copy of the document with the source listings added. 

USE OF THE DOCUMENTATION PROGRAM 

The documentation program is used to generate the entire document. It is keyword 
oriented, with 26 keywords that control the program. Seventeen of those keywords are 
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recognized by the flowchart generator, three are related to text generation, and three have 
to do with control card and deck displays. The programmer who uses the documentation 
program prepares his document on data cards. This is the major drawback of the documen- 
tation program because all input is contained on 80-column card images that must be pre- 
pared by the programmer. The program cannot yet generate text narratives by inspecting 
source decks. 

Repetitive use of the documentation program helps each programmer become more 
familiar with both this particular program and program documentation in general. The key- 
word cards are very easy to understand and prepare, and most programmers become adept 
at using the program after their first try'. The strongest advantage offered by the documen- 
tation program is that it produces the entire document. The document is prepared on 35-mm 
microfilm, which is easy to store, and letter-size reproductions can be made inexpensively on 
bond paper. The following is a list of features of the documentation program: 

(1 ) Text generator— the program can delimit sections of a document at three levels: 
topics, subtopics, and paragraphs. 

(2) Flowchart generator— the flowchart generator is activated when the program reads 
a flow card (one of the 1 7 flowchart keywords). Subsequent cards are inspected 
for special keywords that pertain to flowcharting. Flowcharting terminates when 
an exit card is read. The flowchart generator can be called as many times as 
desired. 

(3) Coding form displays— cards can be displayed singly or in groups on a coding form 
display which numbers each column. 

(4) Deck displays— the deck option operates exactly like the card option, with one 
added feature: After the coding form display has been completed, the deck option 
will cause all displayed cards to be shown in a fanned-deck pictorial representation. 
This type of display gives quick information about card orders to personnel re- 
sponsible for job preparation. 

(5) Underlining -any line of text can be underlined for particular emphasis of impor- 
tant words or phrases. 

(6) Sample output display— the programmer can include a binary coded decimal file 
containing sample tab outputs of his program. The documentation program will 
automatically include the samples in the document when it reads an output card. 

(7) Auxiliary tape input— a keyword card will cause the program to switch from the 
standard input file (usually the card reader) to any other sequential file for pri- 
mary input card images. 

(8) Index— an index of all topics, subtopics, and paragraphs is provided at the end of 
the document that gives page numbers of all sections of the document. 

To aid the programmer in checking the output of the documentation program, a tab 
listing is provided that gives the results of the run. Usually, the microfilm output file is 
stored on tape; the programmer can direct this file to the microfilm unit after he has checked 
the tap output and is satisfied that his document is correct. The tab listing shows the con- 
tents of each frame of output generated by the documentation program. Flowcharts are also 
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printed to show exactly how they will appear on the film. Figure 1 contains a sample pro- 
gram output. 

FUTURE DEVELOPMENTS 

The features of the described documentation program are options; for example, the user 
does not have to use the flowchart generator. Thus, program documentation is still controlled by 
the programmer. To prevent too many stylized documents from being generated, the docu- 
mentation program is supplemented by a set of documentation standards to which all pro- 
grammers must adhere. Because the documentation program itself is in total control of the 
various formats of its options, program documentation has become fairly standardized; at 
least the formats are similar, although content and quality are still the responsibility of the 
programmer. 

It is clear that this system uses a traditional rather than a new or radical approach to 
the problem of documentation. However, these methods suit Grumman’s internal needs. 


GRUMMAN DATA SYSTEMS 


1.0 ocnCRal Information 

PROGRAM NAME PR I NAP I 

WRITTEN BY R. manney 

DECK NO. D047B CSRA 14022 

SOURCE LANGUAGE FORTRAN EXTENDED 

COMPUTER CDC-G400 (ATS. PLT. 7) 


Figure 1 .—Illustration of documentation program. 
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2.0 GENERAL DESCRIPTION 

PRIN4P I WILL PROVIDE LISTINGS OF SELECTEO PARAMETERS * FROM THE 4P I E.U. 

TAPE) AT VARIABLE PRINT RATES ( SAMPLE S/SEC .> . THE LISTINGS ARE CONTROLLED 
BY START-STOP TIMES (IRIG B>. SELECTED PARAMETERS ARE DEFINED BY DATA 
CARDS, UP TO 50 PARAMETERS CAN BE HANDLED AT ANY ONE TIME. IF MORE ARE TO 
BE PRINTED. A REWIND CARD WILL ALLOW THE USER TO RE-START WITH A NEW SET OF 
SELECTED PARAMETERS. 

2. 1 SUBPROGRAM DESCRIPTIONS 

2. 1 . 1 EUPROC 

EUPROC IS THE MAIN PROGRAM. IT READS ALL DATA CARDS AND CONTROLS THE 
FLOW OF DATA. IT ISSUES CALLS TO OTHER SUBROUTINES TO PERFORM SPECIFIC 
FUNCTIONS SUCH AS - DATA CARD DIAGNOSTICS. DATA INPUT. PRINT OUTPUT, MATH 
SUT'M AR I E S . 

2. 1.2 EUPRCD 

EUPRCP INSPECTS THE DATA CARDS FOR NON-EXISTENT PARAMETERS. WHEN ILLEGAL 

parameters cthose not on tape) are found, thcy are simply deleted and an 

APPROPRIATE MESSAGE IS PRINTED. 

2. 1. 3 DATAIN 

PATAIN READS THE 4P I E.U. TAPE AND PASSES ThE SELECTED PARAMETERS TO EUPROC 
FOR FURTHER PROCESSING. IT ALSO RETURNS A FLAG SIGNIFY ING Tt-€1 EN0 OF A 
RUN. 

2. I. A PCI-riA 

PCM1A PERFORMS MATHEMATICAL SUMMARY OPERATIONS AND LIMIT CHECK I NG (WHERE 
REQUESTED) DURING EACH RUN. 

2. 1.5 MATH) 

MATH1 is CALLED by PCMMA DURING A RUN (TIME SLICE), ONCE FOR EACH SAMPLE OF 
EACH PARAMETER. 

2. 1 . 6 MATHO 

MATHQ IS CALLED by PCMMA AT THE END OF A RUN. IT LISTS THE RESULTS OF THE 
MATHEMATIC SUMMARY TAKEN ON EACH PARAMETER DURING THE RUN. AMONG THE 
VALUES LISTED FOR EACH PARAMETER ARE - 

A. MINIMA fM VALUE AND TIME OF OCCURRENCE 

B. MAXIMUM VALUE AND TIME OF OCCURRENCE 

C. STANDARD DEVIATION 

D. MEAN VALUE 

E. ROOT -me AN -SQUARE VALUE 

F. NO. SAMPLES OVER LIMIT (IF APPLICABLE) 

G. NO. SAMPLES UTJDER LIMIT (IF APPLICABLE) 

H. TOTAL NO. SAMPLES OUTSIDE LIMITS 

I. PERCENT OVER LIMIT 


2 - 


1 


Figure 1 (continued).— Illustration of documentation program 
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2. 0 SCNCRAI. DESCRIPTION <CONTO. ) 


J. PERCENT UNDER LIMIT 

2. 1.7 PCMPR 

PCMPR SAVES PRINT VALUES AT THE RATE IS) SPECIFIED. WHEN AO SAVED VALUES 
ARE ACCUMULATED, PCMPR ISSUES A CALL TO OUTPUT TO EMPTY THE BUFFER IS >. 

2. 1. 8 OUTPUT 

OUTPUT LISTS THE SAMPLES SUPPLIED BY PCMPR ON THE OUTPUT FILE. AO LINES OF 
DATA MAXIMUM. 


2 - 


2 


Figure 1 (continued).— Illustration of documentation program. 
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4 PI PRINT - FUNC T I ONAL FLOWCHART 
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Figure 1 (continued).— Illustration of documentation program. 
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Grumman data systems 


* pi print - functional flowchart <contd. i 



s- s 


Figure 1 (continued).-Illustration of documentation program. 
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4 . O CARO FORMATS 


The cards displayed in this section are recognized by the program, all 
0Th E* CARDS WILL BE REJECTED. 


4 - 1 TITLE CARO 

ThC TITLE CARD SHOULD BE Th€ FIRST CARD IN Th£ DECK. IT CONTAINS A TITLE 
WHICH WILL APPEAR AT T^€ TOP OF EACH PAGE OF OUTPUT. 


1 

L*.3A5i6.7,e,a,o| 

l'A5.«.5|S 1 7,8 1 S 1 o| 

4 

1,2,3,4,516,7,8,9,0 

5 

t A3, 4,516,7,0, 9,0 

6 

1 A3, 4,516,7,8,9,0 


8 

1 A 3,4, 5t 6, 7, 8, 9,0 

isoosa— i 



1 1 1 1 I 1 i 1 1 


i i i « 1 i ■ « « 

B— 



CPUS . CE NT ER 

1 -5 title 

11-72 TITLE TO APPEAR AT TOP OF EACH PAGE OF OUTPUT 


4. 2 TIfC SLICE CARD 

THC TIME CARD DEFINES THE IRIG START -STOP TIMES FOR A RUN. IT ALSO ALLOWS 
THE USER TO INHIBIT THE MATH SLMMARY WHICH IS COMPILED DURING Tl-C RUN, 

ANO < IF DESIRED) TO SPECIFY ONE PRINT RATE FOR ALL PRINT PARAMETERS. 


sample Tire CARD 

* I Z 


1 

JAM, 516 , 7 , 8 , 9,0 

1 . 2 . 5 , 1 , 514 , 7 , 8 . 9,0 

1 , 2 , 5 , 1 , 5 , 6 , 7 , 8 , 9, 3 

4 1 

1 , 2 , 3 , 4 , 516 , 7 . 9 , 9,0 

5 

1 . 2 , 5 , 4 , 516 , 7 , 8 , 9,0 

6 

1 ^, 3 , 4 , 516 , 7 , 0 , 9,0 

7 1 

1 A 3 . 4 . 516 . 7 , 0 , 9.0 

0 

'A 3 , 4 , 516 , 7 , 8 , 9,0 

1— 1 

nvnnvn 


— 1 

— V— 



»«««>«»«» 1 

« « i « 1 » « t > 


COLS. 

1 -4 
t 1 - 12 
14- IS 
17-22 

2S-26 
28-29 
31 -36 


CONTENTS 

time 

start TIME IN HOURS 


STOP TIME IN HOURS 


< 11 - 12 ),. MIN 


(25-26) . MIN 


(14-15) , 


(20-29) . 


SECS (17-22) 


SECS (31-36) 


41 MATH INHIBIT FLAG 

» 1 , NO MATH OUTPUT AT END OF SLICE 
46-51 OVERALL PRINT RATE (MUST INCLUDE DEC. PT. ) 

IN SAMPLES /SECOND 


4- 


1 


Figure 1 (continued).— Illustration of documentation program. 





52 


AUTOMATED METHODS OF COMPUTER PROGRAM DOCUMENTATION 


GRUMMAN DATA SYSTEMS 


4. 0 CARO FORMATS <CONTO. » 


4. s PRINT CARO SETS 

A print card set specifies up to five parameters to be printed on A SINGLE 
page of output. it also specifies the print RATE IS/S) for that page, up 

to 10 PRINT SETS CAN BE ACTIVE DURING A GIVEN TIME SLICE. 


SAMPLE PRINT SET (EACH SET MUST HAVE TWO CAROS) 
1| 2, 3, 4, 


■2.5.«.w.8.9 .0 '.2.V.SIS.7.8.9.0 1.Z.5, «.S|g,7.8.9.0 1.2.M.S|6,7.8.9.0 


i.2,3.4.S|g.7,e,9.0 


S| 6 7 e 

I.g.i.«.5l6.7.8.9,e 1.2,i.4.S|6.7.8.9.0 1.2.5.«.5|t.7,8,9,0. 


PRINT 


J_l_ 


IS. , 

* i-i l 1 i i t i 


PAR AI-^TER 1 


Li— Li-i- 


_Lj 


PARA^ETERa 


i l l i I ii. 


l i I lilt 


*ARAM£TER3 

I t i t li i i i 1 


i » i i I i i i i 


■ dim 




J I L-UL. 


j.m I u. 




FORMAT or FIRST CARD 

COLS. CONTENTS 

1 -5 PRINT 

11-14 RATE (MUST INCLUDE DECIMAL PT. ) IN SAMPLES /SECOND 

THIS FIELD IS OPTIONAL (IF OVERALL PRINT OPTION ON 
TIME CARD WAS USED FOR CURRENT TIME SLICE) 

21-30 MNEMONIC FOR FIRST PARAMETER 

51-60 MNEMONIC FOR SECONO PARAMETER 

FORMAT OF SECOND CARD 

COLS. CONTENTS 

1-10 THIRD PRINT PARAMETER MNEMONIC 

31-40 FOURTH PRINT PARAMETER MNEMONIC 

61-70 FIFTH PRINT PARAMETER MNEMONIC 

4. 4 LIMIT DECKING 

any parameter on the tape (Independent of those printed) can be limit 

O-CCKED. ThC RESULTS WILL BE ADDED TO THE MATH SUMMARY AT Ti-C END OF The 
RUN. 

sample limit card 








7 

I*2.3,4.5i6.7,8,9,0 

8 

1.2.3.4.516.7,8,9,0 



114 .III.. 

■wm nm 


»»«»!■««« 

-i. llllilll 



COLS. CONTENTS 


if -5 

jl mu. 



1 1 -20 

PARAMETER memon I c 


31 -40 

LOWER LIMIT 

(in ENGINEERING 

UNI TS) 

41 -50 

UPPER LIMIT 

(IN ENGINEERING 

UNITS) 


4- 


2 


Figure 1 (continued).-Illustration of documentation program. 
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4. 0 CARD FORMATS ‘CONTO. ) 


4. S EWTIME CARD 

ThC ENDTIME CARO IS USED BETWEEN TIME SLICES WHEN AN ENTIRELY NEW SET OF 
PRINT ANO/OR LIMIT PARAMETERS IS TO BE OUTPUT. 


SAr*»t_E E NOT I ME CARD 


wmmm 


mu 






\3 ssnsmm 

livvnnvn 

HHVWVH 

■MiMi 


hhuhh 

H 9 HVHH 

HWHWH 

HWWWVI 


COLS. 1-7 CONTAIN THE CHARACTERS ENDTIME . 

4. 6 Tt-E REWIND CARD 

Tl-C REWIND CARD WILL CAUSE TNE PROGRAM TO REWIND THE INPUT TAPE IS) TO LOAD 
POINT AND REINITIALIZE ALL ARRAYS. THEN THE PROGRAM WILL BEGIN READING 
CARDS AGAIN. Tt-E REWIND SHOULD APPEAR AFTER AN ENDTIME CARD TO ALLOW TNE 
PREVIOUS TIME SLICE TO GO TO COMPLETION. 

4. 7 STOP CARO 

THE STOP CARD TERMINATES THE RUN. IT CONTAINS THE LETTERS STOP IN COLS 1-4 


4- 


s 


Figure 1 (continued).— Illustration, of documentation program. 
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•. e occk set-ups 


S. I DATA OCCK (MTUE 

th e sample shown below inoicates a typical deck set-up. note the first 
ENpT ire CARD AND The NEW SET OF PRINT/LIMIT CARDS WHICH follow it. 
EXPLANATION OF SAMPLE DATA DECK 

TIME SLICE I <4/15/11.6 TO 4/1 6/22. 3) WILL OUTPUT AS FOLLOWS - 
PAGE 1 PARAM NOS. I. 2, AND S 

PAGE Z PARAM NOS. 4 AND 5 

LIMIT CHECKING TO BE DONE ON PARAMS Z AND S 
TnC ABOVE OUTPUT GROUPS WILL BE RETAINED FOR TIME SLICES Z AND S WITH TIME 
SLICE 3 DOING. ADDITIONALLY. LIMIT CHECKING ON PARAMS 1 A NO 3 
TIME SLICE 4 16/13/12. TO 6/13/30.) WILL OUTPUT AS FOLLOWS - 
PAGE 1 PARAM NOS. 3. 7. 9, AND 2 

PAGE H PARAM NOS. S AND 6 

LIMIT CHECKING ON PARAM NO 4 



Figure 1 (continued).— Illustration of documentation program. 
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S. O DECK SET-UPS <CONTO. I 


SAMPLE DATA CAPOS 






B5uwBBu8eg 



HUHHb 

imwwni 

HHUHH 

HHUHH 



HVHHVH 

mmm 

HVHHVH 

iSSOTHH 

fWWliwil 

hvhhvh 


HHGVHVI 

hhhhh 

HHVHHI 

Hyvvvivii 


hvwvwh 

HHHHH 


HHUHH 

HHHHH 

HVHHVH 

hvhvhh 

□OMH 

hvhhvh 

HVHHVH 

hhhhh 

HVHHHI 

hhhhh 

HHHVIH 

hvhhvh 

IIEWDSEV 

H5VU2V05! 

jhhhvh 

HHVHHI 

hvhhvh 

hhhhh 

HHVHHI 

hvhhvh 


B- 


* 


Figure 1 (continued).— Illustration of documentation program. 
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12 



SA MPLX data ca*os 


«- 


3 


Figure 1 (continued).— Illustration of documentation program. 
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*. 0 OCCK SET-UPS <CONTD. > 


s. z joe occk sample 

SAMPLE 4PI PRINT^JOe DECK 

7|8.9,o|l,2.J.».S|6.1.8 1 3 1 o|l 





Figure 1 (continued). -Illustration of documentation program. 
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t . 0 


GENERAL i format I on 

1 

2. 0 


GENERAL DESCRIPTION 

2 

2. 


SUBPROGRAM DESCRIPTIONS 

2 

2. 


» euproc 

2 

2. 


2 EUPRCD 

2 

2. 


3 DataIn 

2 

2. 


A PCMMA 

2 

2. 


5 mathi 

2 

2. 


G MAT HO 

2 

2. 


7 PCMPR 

3 

2. 

t . 

0 OUTPUT 

3 

S. C 

i 

A PI print - functional flowchart 

4 

A. 0 

CARO FORMATS 

7 

4. 

1 

TITLE CARO 

' 

4. 

2 

time slice card 

7 

4. 

3 

PRINT CARD SETS 

9 

4. 

4 

limit checking 

a 

A. 

s 

endtime, card 

9 

4. 

6 

the rewind card 

9 

4. 

7 

STOP CARO 

9 

5. 

0 

DECK SET-UPS 

1 0 

S. 

\ 

DATA DECK SAMPLE 

' 0 

5. 

2 

U08 OECK SAMPLE 

t 3 


Figure 1 (concluded).-Illustrationof documentation program. 
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DISCUSSION 

MEMBER OF THE AUDIENCE: Would you comment further on the 26 keywords? 
HANNEY: The topic, subtopic, and paragraph keywords are in the text generator. 
There is a card keyword for the coding form and a deck keyword for the deck display. The 
flowchart generator has 17 keywords, one for each symbol. 

MEMBER OF THE AUDIENCE: Are the numerical displays used for text generation 
or simply stored on cards? 

HANNEY: There are cathode ray tube (CRT) displays at the automated telemetry sta- 
tion, and we have a command program that interacts with the CRT unit. The user at this 
station can create a display code file and send it to the documentation programmer. It would 
then be stored on a disk file and inserted in the program later. 



